From: Florian Müllner <fmuellner@gnome.org>
Date: Fri, 29 Nov 2024 17:00:29 +0000 (+0100)
Subject: tools/toolbox: Document new sysext tooling
X-Git-Tag: archive/raspbian/50.5-1+rpi1~1^2~173^2^2~143
X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/%22/%22http:/www.example.com/cgi/%22?a=commitdiff_plain;h=4847d8bc954c0cf1fbcfa5d45465c8ee014f49de;p=gnome-shell.git

tools/toolbox: Document new sysext tooling

Add a small section to outline how to combine `meson-build.sh --sysext` and
`toolbox-sysext-install.sh` to install a system extension from our toolboxes.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3498>
---

diff --git a/tools/toolbox/README.md b/tools/toolbox/README.md
index 3b695db2d..e4bbb816e 100644
--- a/tools/toolbox/README.md
+++ b/tools/toolbox/README.md
@@ -57,9 +57,39 @@ simulating multiple monitors or a greeter session.
 
 Run the script with `--help` to see all available options.
 
+## toolbox-sysext-install.sh
+
+Extract a prepared system extension directory from the toolbox and
+install it as [systemd-sysext] extension on the host.
+
+The `meson-build.sh` script has a `--sysext` option to easily add
+projects to the extension directory in the toolbox:
+
+```sh
+  $ cd path/to/mutter; meson-build.sh --sysext
+  $ cd path/to/gnome-shell; meson-build.sh --sysext
+  $ toolbox-sysext-install.sh
+```
+
+System extensions require that the host operating system matches
+the extension. For toolboxes created with the `create-toolbox.sh`
+script this means the most recent Fedora release.
+
+### Important note
+
+gnome-shell is tightly coupled with mutter, so an extension that
+only contains gnome-shell is very likely to fail. The `update-mutter`
+command inside the toolbox already takes care of this, but when
+building mutter manually, it is the responsibility of the caller
+to ensure that the system extension contains a recent-enough
+mutter build.
+
+Run the script with `--help` to see available options.
+
 [toolbox]: https://containertoolbx.org/
 [mutter]: https://gitlab.gnome.org/GNOME/mutter
 [builder]: https://apps.gnome.org/Builder/
 [meson]: https://mesonbuild.com
 [handbook]: https://handbook.gnome.org/
 [troubleshooting]: https://handbook.gnome.org/development/toolbx.html#when-things-go-wrong
+[systemd-sysext]: https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html